Version: 1.3.0

Chat API Documentation

Chat Retrieval Endpoint

Method: POST
Path: https://api.kadal.ai/aiwb/chat/api/v7/
Summary: Retrieves chat history for a specific bot with optional filtering and pagination.

Description

Retrieves chat history for a specific bot with optional filtering and pagination.

Request

Content-Type: application/json
Query Parameters

| Name | Description | Type | Constraints| Required | | ---- | ---- | ---- | ---- | | chat_bot_id | Chatbot identifier | UUID | | Yes | | page_no | Page number | number | Min: 1 | | | page_size | Number of records per page | number | Min: 1 | | | order | Sort order | string | ["asc", "desc"] | |

Payload

Field	Description	Type	Constraints
text	Search text in queries/responses	string	Optional
created_by	Filter by user ID	string	Optional, Valid user ID

Response

Success (200 OK)

{
  "status_code": 200,
  "message": "Chat history fetched successfully",
  "total_count": 1,
  "data": {
    "has_continuations": false,
    "chat_hist": [{
      "_id": "string",                    // MongoDB ObjectId
      "tenant_id": "string",              // UUID
      "user_id": "string",
      "object_id": "string?",
      "user_query": "string",
      "bot_response": "string",
      "chat_bot_id": "string",            // UUID
      "user_type": "internal|external",
      "is_cleared": "integer",               // 0 or 1
      "creation_time": "string",          // ISO8601
      "response_time": "string",          // ISO8601
      "metadata": {
        "category": "chat|event"
      },
      "is_positive": "boolean?",
      "query_response_id": "string",
      "chat_bot_name": "string"
    }]
  }
}

Other Responses

No Records Found Response

{
  "status_code": 404,
  "message": "No chat record found",
  "total_count": 0,
  "data": {
    "has_continuations": false,
    "chat_hist": []
  }
}

Usage

import requests

url = "https://api.kadal.ai/aiwb/chat/api/v7/"
token = "your_token_here"

headers = {
    "Authorization": f"Bearer {token}",
    "Content-Type": "application/json"
}

params = {
    "chat_bot_id": "bot-uuid-here",
    "page_no": 1,
    "page_size": 10,
    "order": "asc"
}

data = {
    "text": "search query",
    "created_by": "user123"
}

response = requests.post(url, headers=headers, params=params, json=data)

if response.status_code == 200:
    print("Chat History:", response.json())
else:
    print("Error:", response.status_code, response.text)

Chat Download Endpoint

Method: POST
Path: https://api.kadal.ai/aiwb/chat/api/v7/download/

Description

Downloads chat history as a PDF file for a specific bot. Returns a URL to access the generated PDF.

Request

Content-Type: application/json

| Name | Description | Type | Constraints| Required | | ---- | ---- | ---- | ---- | | chat_bot_id | Chatbot identifier | UUID | | Yes | | object_id | Associated object identifier | string | Max length: 100 | No | | ext_ref_user_id | External reference user ID | string | Max length: 100 | No | | text | Search text in queries/responses | string | Max length: 500 | No | | created_by | Filter by user ID | string | Valid user ID | No |

Response

Success Response

{
  "message": "PDF uploaded to S3 successfully",
  "file_url": "https://kadal.ai/chat_history/{tenant_id}/{filename}"
}

Other Responses

{
  "status_code": 404,
  "message": "No chat record found",
  "total_count": 0,
  "data": {
    "has_continuations": false,
    "chat_hist": []
  }
}

Usage

import requests

url = "https://api.kadal.ai/aiwb/chat/api/v7/download/"
token = "token-here"


headers = {
    "Origin": "https://kadal.ai",
    "Authorization": f"Bearer {token}"
}

query_params = {
    "chat_bot_id": "bot-uuid-here"
}

response = requests.post(url, headers=headers, params=query_params)

if response.status_code == 200:
    print("Download URL:", response.json())
else:
    print("Error:", response.status_code, response.text)

Chat Clear History Endpoint

Method: POST
Path: https://api.kadal.ai/aiwb/chat/api/v7/clearhistory

Description

Clears chat history for a specific bot with optional filtering.

Request

Content-Type: application/json
Parameters

Name	Type	Required	Description	Constraints
chat_bot_id	UUID	Yes	Chatbot identifier	Valid UUID format
object_id	string	No	Associated object identifier	Max length: 100
ext_ref_user_id	string	No	External reference user ID	Max length: 100

Response

Success Response

{
  "status_code": 200,
  "message": "Previous conversations deleted successfully",
  "query_response_id": null,
  "finish_reason": ""
}

Other Responses

{
  "status_code": 404,
  "message": "Agent wasn't found.",
  "query_response_id": "",
  "finish_reason": "no_bot_found"
}

Usage

import requests

url = "https://api.kadal.ai/aiwb/chat/api/v7/clearhistory"
token = "your_token_here"

headers = {
    "Authorization": f"Bearer {token}",
    "Content-Type": "application/json"
}

params = {
    "chat_bot_id": "bot-uuid-here",
    "object_id": "obj123",
    "ext_ref_user_id": "user123"
}

response = requests.post(url, headers=headers, params=params)

if response.status_code == 200:
    print("History cleared:", response.json())
else:
    print("Error:", response.status_code, response.text)

Stream Chat Endpoint

Method: POST
Path: https://api.kadal.ai/aiwb/chat/api/v7/{chat_bot_id}/stream

Description

Streams chat responses with support for file handling and tool configurations.

Request

Content-Type: application/json
Path Parameter

Name	Description	Type	Constraints	Required
chat_bot_id	Chatbot identifier	UUID	-	Yes

Query Parameter

Name	Description	Type	Constraints	Required
stream	Enable token-by-token streaming	boolean	Default: false	No
continue_last_chat	Continue previous context	boolean	Default: false	No
object_id	Associated object identifier	string	Default: null	No

Payload

{
  "message": "string",
  "is_tool_calling": false,
  "metadata": {
    "category": "chat"  // See metadata types below
  }
}

Metadata Types

Basic Chat

{
  "category": "chat"
}

File Processing

{
  "category": "event",
  "type": "file",
  "files": [{
    "file_name": "string",
    "file_type": "string",
    "object_id": "string?",
    "folder_id": "string?",
    "source_category": "InputFile|ContextFile|KnowledgeBase|Guideline|OutputTemplate",
    "input_type": "Repository|Computer|GDrive"
  }]
}

Tool Configuration

{
  "category": "event",
  "type": "tool",
  "message": "string",
  "tool_config": {
    "web_search": "boolean",
    "content_lake": "boolean"
  }
}

Model Switch

  "metadata": {
    "category": "event",
    "type": "verbose",
    "message": "string",
    "modelId" : "string",
    "modelVersion": "string"
}

Response

Non-streaming Response (application/x-ndjson)

{"status_code":200,"message":"Response message","session_id":null,"query_response_id":"68ac044e3b3b0e000a5a7dc8","finish_reason":"stop"}

Streaming Response (application/x-ndjson)

{"status_code":200,"message":"The","session_id":null,"query_response_id":"68ac01bdf0cf707600c0f655","finish_reason":"streaming"}
{"status_code":200,"message":" phrase","session_id":null,"query_response_id":"68ac01bdf0cf707600c0f655","finish_reason":"streaming"}
{"status_code":200,"message":" \"","session_id":null,"query_response_id":"68ac01bdf0cf707600c0f655","finish_reason":"streaming"}
{"status_code":200,"message":"Mary","session_id":null,"query_response_id":"68ac01bdf0cf707600c0f655","finish_reason":"streaming"}
{"status_code":200,"message":" had","session_id":null,"query_response_id":"68ac01bdf0cf707600c0f655","finish_reason":"streaming"}
{"status_code":200,"message":" a","session_id":null,"query_response_id":"68ac01bdf0cf707600c0f655","finish_reason":"streaming"}
{"status_code":200,"message":" little","session_id":null,"query_response_id":"68ac01bdf0cf707600c0f655","finish_reason":"streaming"}
{"status_code":200,"message":" lamb","session_id":null,"query_response_id":"68ac01bdf0cf707600c0f655","finish_reason":"streaming"}
{"status_code":200,"message":"\"","session_id":null,"query_response_id":"68ac01bdf0cf707600c0f655","finish_reason":"streaming"}
{"status_code":200,"message":" contains","session_id":null,"query_response_id":"68ac01bdf0cf707600c0f655","finish_reason":"streaming"}
{"status_code":200,"message":" ","session_id":null,"query_response_id":"68ac01bdf0cf707600c0f655","finish_reason":"streaming"}
{"status_code":200,"message":"5","session_id":null,"query_response_id":"68ac01bdf0cf707600c0f655","finish_reason":"streaming"}
{"status_code":200,"message":" words","session_id":null,"query_response_id":"68ac01bdf0cf707600c0f655","finish_reason":"streaming"}
{"status_code":200,"message":".","session_id":null,"query_response_id":"68ac01bdf0cf707600c0f655","finish_reason":"streaming"}
{"status_code":200,"message":"#","session_id":null,"query_response_id":"68ac01bdf0cf707600c0f655","finish_reason":"stop"}

Other Responses

{
  "status_code": 200,
  "message": "The context is too lengthy for effective processing. Please revise your templates, guidelines, or instructions to make them more concise, or upload a smaller file.",
  "finish_reason": "input_exceeded_context_window"
}

Safety Guardrail Hit

{
  "status_code": 200,
  "message": "Sorry, the model cannot answer this question due to harmful or sensitive information. This will be recorded as a violation, and your administrator will be notified.",
  "finish_reason": "guardrail_hit"
}

Usage

import requests

url = "https://api.kadal.ai/aiwb/chat/api/v7/{chat_bot_id}/stream"
token = "your_token_here"

headers = {
    "Authorization": f"Bearer {token}",
    "Content-Type": "application/json"
}

params = {
    "stream": True,
    "continue_last_chat": False
}

data = {
    "message": "Hello",
    "is_tool_calling": False,
    "metadata": {
        "category": "chat"
    }
}

response = requests.post(url, headers=headers, params=params, json=data, stream=True)

for line in response.iter_lines():
    if line:
        print(line.decode())

Chat Feedback Endpoint

Description

Submits feedback for chat interactions with optional metadata and details.

Method: POST
Path: https://api.kadal.ai/aiwb/chat/api/v3/feedbacks

Request

Content-Type: application/json
Payload

Name	Description	Type	Constraints	Required
chatbotId	Bot identifier	string	UUID format	No
consumerId	Consumer ID	integer	-	No
keycloakConsumerId	Keycloak consumer ID	string	UUID format	No
tenantId	Tenant ID	integer	-	No
keycloakTenantId	Keycloak tenant ID	string	UUID format	No
reason	Feedback reason	string	One of ["pre-defined", "other"]	No
details	Detailed feedback	string	Max length: 1000	No
user_query_id	Query ID	integer	-	No
query	Original user query	string	Max length: 500	No
metadata	Additional metadata	object	-	No

{
  "chatbotId": "string?",              // UUID format
  "consumerId": "number?",             // Integer
  "keycloakConsumerId": "string?",     // UUID format
  "tenantId": "number?",               // Integer
  "keycloakTenantId": "string?",       // UUID format
  "reason": "string?",                 // Pre-defined or custom
  "details": "string?",                // Detailed feedback
  "user_query_id": "number?",          // Integer
  "query": "string?",                  // Original user query
  "metadata": {                        // Optional metadata
    "source": "string?",
    "version": "string?"
  }
}

Response

Success Response

{
  "status": "success",
  "message": "Feedback submitted successfully",
  "document_id": "67eba353969855dc98a85e37"
}

Other Responses

{
  "status_code": 400,
  "message": "Invalid request format",
  "error": "VALIDATION_ERROR"
}

Usage

import requests

url = "https://api.kadal.ai/aiwb/chat/api/v3/feedbacks"
token = "your_token_here"

headers = {
    "Authorization": f"Bearer {token}",
    "Content-Type": "application/json"
}

data = {
    "chatbotId": "550e8400-e29b-41d4-a716-446655440000",
    "consumerId": 8,
    "reason": "pre-defined",
    "details": "Not factually correct",
    "query": "What are the main features?",
    "metadata": {
        "source": "web",
        "version": "1.0.2"
    }
}

response = requests.post(url, headers=headers, json=data)

if response.status_code == 201:
    print("Feedback submitted:", response.json())
else:
    print("Error:", response.status_code, response.text)

Chat Retrieval Endpoint​

Description​

Request​

Query Parameters​

Payload​

Response​

Success (200 OK)​

Other Responses​

No Records Found Response​

Usage​

Chat Download Endpoint​

Description​

Request​

Response​

Success Response​

Other Responses​

Usage​

Chat Clear History Endpoint​

Description​

Request​

Parameters​

Response​

Success Response​

Other Responses​

Usage​

Stream Chat Endpoint​

Description​

Request​

Path Parameter​

Query Parameter​

Payload​

Metadata Types​

Response​

Non-streaming Response (application/x-ndjson)​

Streaming Response (application/x-ndjson)​

Other Responses​

Safety Guardrail Hit​

Usage​

Chat Feedback Endpoint​

Description​

Request​

Payload​

Response​

Success Response​

Other Responses​

Usage​

Chat Retrieval Endpoint

Description

Request

Query Parameters

Payload

Response

Success (200 OK)

Other Responses

No Records Found Response

Usage

Chat Download Endpoint

Description

Request

Response

Success Response

Other Responses

Usage

Chat Clear History Endpoint

Description

Request

Parameters

Response

Success Response

Other Responses

Usage

Stream Chat Endpoint

Description

Request

Path Parameter

Query Parameter

Payload

Metadata Types

Response

Non-streaming Response (application/x-ndjson)

Streaming Response (application/x-ndjson)

Other Responses

Safety Guardrail Hit

Usage

Chat Feedback Endpoint

Description

Request

Payload

Response

Success Response

Other Responses

Usage